Global (User Defined) Functions

Similarly, you can define your own functions by writing Xbasic code. But unlike object events, which are already named, you can name your own functions. Once created you can call on that function to accomplish something that you need to repeat. It does not make sense to create a function that is only used once for a very specific task. When you have to manipulate data in a custom way that is not provided by a pre-built Xbasic function and you have to do it over and over, that is the time to create your own function.

Once a function is created and named, it becomes part of your own Alpha Anywhere set of functions. You have previously seen that one of the selections for function categories is User Defined. These functions are also called global functions. Once created, they are available to be used in any of your Alpha Anywhere applications.

A global function is like an Xbasic command of your own creation. It has a name, it can accept parameters and it can (optionally) return a value. Global functions have to meet certain criteria in order to function correctly. Alpha Anywhere makes it easy to build-your-own functions.

Let's take a quick look at a global function written for the Its For You application.

The Its For You application stores the names of message takers and receivers in the message_tr table. This table shows the fields from message_tr that store a persons name data along with a sample record from the table.

In the Its For You application, a persons name is used in selection lists, reports and input forms. There are multiple ways to format a persons name from the available data fields. For example, for the data above, you might want to use the name in the following formats:

The Its For You application includes three functions that return formatted strings as Per the above table. The first lines of the Xbasic code that defines these functions are shown below:

FUNCTION fullfamiliarname as C (familiar as C, lastname as C )
FUNCTION fullformalname as C (salutation as C, firstname as C, middlename as C, lastname as C, suffix as C)
FUNCTION trimmedName as C (firstName as C, lastName as C )

The full function code for fullfamiliarname() is shown below:

This function take two character string parameters as inputs (they are local variables named familiar and lastname ). It applies the alltrim() built-in function to each string to trim off leading and trailing blanks and then combines these values with one blank space to return a formatted name. This name string is assigned to the variable fullfamiliarname. It is returned to the expression that invoked the function.

The function fullfamiliarname() can be called from any expression in Alpha Anywhere. Here is an example of it being called from the Interactive window:

Two character strings, "Penelope " and " Snodgrass" , are input to the function and the formatted name string is output to the screen.

In the Administration form of the Its For You application, three fields on the screen display formatted versions of the users name. Below, you see the Calculated Fields dialog box superimposed over the Administration form.

1. Click on the Code tab of the Control Panel window.

2. Click on the New button and then choose Function shown in figure 70.

   

3. For the Function Name enter:

   fnadmin

4. Leave the Return Type as "Character".

5. Enter the following three arguments (parameters) for the function:

   • fname

     Character

   • lname

     Character

   • admin

     Logical

   • 

6. Press OK to save the function definition. Alpha Anywhere opens the Code Editor and displays a prototype of the function. A prototype is the shell of a function without any Xbasic commands to process it. The prototype tells you what type of value the functions returns and what parameters (and parameter types) the function expects as input.

   

   Alpha Anywhere adds an open and close parenthesis to the function name to differentiate a function from a script.

   The FUNCTION command opens with the word FUNCTION followed by the name, the word AS, and the type of the return value. Next is a parentheses, any parameters (expressed as Parameter name, the word AS, and the type of the parameter), a comma to separate multiple parameters, and a closing parentheses. (If there are no input parameters, you still need the open and close parentheses.)

   Next comes your code. Remember, in order for the function to return a value to the calling expression, you must assign that value to a variable with the same name as the function. Finally, the function definition ends with the END FUNCTION command.

7. Enter the following four lines between the FUNCTION ... and END FUNCTION lines.

   fnadmin = alltrim(fname) + " " + alltrim(lname)
   if admin then
      fnadmin = fnadmin + "(Admin)"
   end if

   When you press Enter after typing the line if admin then, Alpha Anywhere will automatically create the line end if for you.

8. Select Code > Check Syntax. You should see this:

9. Alpha Anywhere can check that the syntax of your script is correct. This is not the same as a logic check. A syntax check means that you typed in the Xbasic commands the correct way and that all the expressions make sense. Whether they give you the result you really want is up to you to judge.

10. Delete the word "FUNCTION" from the last line of the script and select Code > Check Syntax.

    
    Alpha Anywhere responds with an error pop-up message indicating the Xbasic command FUNCTION...END FUNCTION is incomplete.

11. Put the word "FUNCTION" back in.

12. Press Save to save the function.

    After you save the function in Step 11, the * (asterisk) next to the function name in the Code Editor tab will be gone. Whenever an * appears next to a script name in the editor, it indicates you have made changes to that script that you have not yet saved.

13. Press the Interactive tab to see the Interactive window.

14. Enter the following commands:

    dim name1 as C
    dim name2 as C
    dim is_an_admin as L
    name1 = " George"
    name2 = "Michael "
    is_an_admin = .T.

15. Now enter the following:

    ? fnadmin(name1, name2, is_an_admin)

16. Alpha Anywhere replies with:

    = George Michael (Admin)

17. Enter the following:

    is_an_admin = .F.
    ? fnadmin(name2, name1, is_an_admin)

    In this invocation of the fnadmin() function, name2 is given as the first parameter and name1 as the second. The function does not care what variables or values you enter as long as the type of the variable matches the parameter definition in the function code. Here, the character string, name2, will be assigned to the parameter, fname, in the function code itself. So name2 will come out first.

18. Alpha Anywhere replies with:

    = Michael George

19. Close the Code Editor.

To recap, most functions you create are called Global functions because they are available to be used in part of your Alpha Anywhere application. However, you can create a local function. A local function is a function defined in a script or another function.

So a function script FUNCTION1 could contain a second function definition named FUNCTION2. Here is the code for FUNCTION1 :

function FUNCTION1 as C (name1 as C, birthdate as D)
  function1 = alltrim(name1)+ +function2(birthdate)
end function
function FUNCTION2 as C (bday as D)
   if age(bday) > 40 then
       function2 = "has already reached the big 4-0"
   else
        function2 = "is still at most 39 years old"
   end if
end FUNCTION

FUNCTION1 calls FUNCTION2. And like a local variable, a local function is only visible or available to the function it is defined within.

Whereas you would be able to call FUNCTION1 from anywhere in Alpha Anywhere, you could not call FUNCTION2 from another script.